---
title: Flatten form fields
summary: Flattens the form fields in a submitted PDF using either the iTextSharp client or the Syncfusion helper.
status: draft
owner: Not determined from source
last_reviewed: 2026-09-17
library: PdfAPI
reference_type: embedded
operation_id: OP-FLATTEN-FORM-FIELDS
trigger: Client submits POST v1/info/fields/flatten with PDF bytes
---

# OP-FLATTEN-FORM-FIELDS: Flatten form fields

Flattens the form fields in a submitted PDF and returns the flattened document bytes, using the caller-selected inspection/flattening client.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-FLATTEN-FORM-FIELDS |
| **Trigger** | Client submits `POST v1/info/fields/flatten` with PDF bytes |
| **Entry endpoint** | [`POST v1/info/fields/flatten`](../endpoints/info-controller.md#post-v1%2Finfo%2Ffields%2Fflatten) |
| **Owning component** | `InfoController.FlattenFormFields(byte[], bool)` → `PdfClientService.Flatten` \| `PdfHelper` (Syncfusion) |
| **Inputs** | Request body: `byte[]` PDF; query: `useClient` (default `true`) |
| **Outputs** | Bare `byte[]` (flattened PDF bytes; base64-encoded string in the JSON response)* |
| **Failure response** | No `try`/`catch` on this action — any exception produces framework exception detail (`IncludeErrorDetailPolicy.Always`) before `ApiResponseHandler` runs; the final client-visible envelope is unknown** (see [Endpoints: Error response shape](../endpoints.md#error-response-shape)) |

## Steps

1. `useClient` (default `true`) selects the flattening implementation ([BR-PDFAPI-021](../business-rules.md#br-pdfapi-021-form-field-inspection-client-selection)):
   - `true` (default): `PdfClientService.Flatten` (iTextSharp) is invoked, which first validates the `%PDF-` signature ([BR-PDFAPI-005](../business-rules.md#br-pdfapi-005-pdf-validity-by-file-signature)).
   - `false`: `PdfHelper.FlattenFormFields` (Syncfusion) is invoked instead.

   `PdfClientService.Flatten` is implemented in `PdfAPI.Core`, documented in full at [Flatten form fields](../../../libraries/pdfapi-core/operations/op-07-flatten-form-fields.md) (OP-07). `PdfHelper.FlattenFormFields` is implemented in `PdfApi.SyncFusionCore`, documented in full at [Inspect and flatten PDF form fields](../../../libraries/pdfapi-syncfusioncore/operations/inspect-and-flatten-pdf-form-fields.md) (OP-SFC-013). Both behaviors are summarized here only as observed on this request path.

   > **Origin:** The `useClient = true` flattening behavior in this step is implemented in
   > `PdfAPI.Core`; the `useClient = false` flattening behavior is implemented in
   > `PdfApi.SyncFusionCore`. See the linked operation pages for the full delegated logic.
2. On the `useClient = true` path, a non-PDF payload raises `PdfException`, which escapes uncaught to the framework, producing exception detail before `ApiResponseHandler` runs; the final client-visible envelope is unknown**.
3. The bare `byte[]` result is returned — HTTP `200`, serialized as a base64 string by the default JSON formatter.

## Process flow

The following diagram shows the client-selection and validation sequence for flattening form fields.

```mermaid
flowchart TD
    A["POST v1/info/fields/flatten"] --> B{"useClient?"}
    B -->|true default| C["PdfClientService.Flatten: iTextSharp"]
    B -->|false| D["PdfHelper.FlattenFormFields: Syncfusion"]
    C --> E{"Valid PDF?"}
    E -->|No| F["PdfException escapes to framework: 500"]
    E -->|Yes| G["Return flattened bytes, 200"]
    D --> G
```

## Transaction and side effects

| Aspect | Finding |
| --- | --- |
| Unit of work | None |
| Commit point | Not applicable — no database access |
| Records written | None |
| Downstream calls | None |
| Repeat-call behavior | Same output for the same input; safe to repeat* |

## Logging

| Surface | Written content |
| --- | --- |
| — | No dedicated logging observed on this path beyond framework-level exception logging on an uncaught failure |

## Error handling

- Non-PDF payload on the `useClient = true` path: `PdfException` escapes uncaught, producing framework exception detail before `ApiResponseHandler` runs; the final client-visible envelope is unknown** ([BR-PDFAPI-005](../business-rules.md#br-pdfapi-005-pdf-validity-by-file-signature); see [Endpoints: Error response shape](../endpoints.md#error-response-shape)).

## Related documentation
- [API index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Endpoints](../endpoints.md)
- [Authentication and authorization](../authentication-authorization.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Data model](../data-model.md)
- [Operational runbook](../operational-runbook.md)
- [Tech debt](../tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with `**` could not be confirmed; treat as unknown until verified.

## Sources
- PdfAPI\Controllers\v1\InfoController.cs
- PdfAPI.Core\Services\PdfClientService.cs
- PdfApi.SyncFusionCore\PdfHelper.cs